home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 1998 February / Macworld (1998-02).dmg / Shareware World / Comms & Internet / ShadowBot 1.23 / Documentation next >
Text File  |  1997-10-05  |  18KB  |  242 lines

  1. ShadowBotConfiguration and Setup
  2. © 1996-1997 John Bafford, all rights reserved.
  3.  
  4. ShadowBot is shareware, $20. To register, send cash, check, or money order to:
  5. ShadowBot Registration
  6. c/o John Bafford
  7. 6 Cedar Springs Ct.
  8. Baltimore, MD 21228
  9.  
  10. If you read this file, you shouldn’t have any problems setting up ShadowBot. PLEASE read this file first because I would much rather spend time coding ShadowBot than answering questions whose answers can be found in this file (or others distributed with ShadowBot).
  11.  
  12. Also, everything has balloon help, which is often better than what's in this documentation.
  13.  
  14. Connection Settings
  15.     This is one of the most important of the configuration windows. Without this window properly set up, ShadowBot cannot connect to an IRC server.
  16.     Nick - This is the bot’s nickname. It must be nine characters or shorter.
  17.     Username - This is the bot’s username.
  18.     Command character - This is the bot’s command character. All commands, with few exceptions, must be preceded by this character so the bot knows you’re talking to it. By unchecking the ‘Required’ checkbox, you can make the command character optional. Commands typed into the console require the command character.
  19.     DCC Command Character - This is the command character used in DCC chat.
  20.     Connect Script - If the Use Connect Script button is checked, the bot executes these (IRC) commands on connection before joining channels.
  21.     Auto-Connect - If this is checked, the bot will automatically log on when it loads up. Press and hold the shift key down while the splash screen is open to temporarally disable this.
  22.     Reconnect to server - Allows the bot to attempt to recnnect to the server on its own when it's disconnected.
  23.     Display MOTD - If unchecked, this supresses the display of the MOTD.
  24.     Use Identd - Allows the bot to use Identd to remove the ~ from the username.
  25.     MODE +d - Makes the bot deaf to channel messages. (The command !deaf has the same effect; the command !hear sets the mode to -d.)
  26.     MODE +i - Makes the bot invisible. (Unless you're on a channel it's on, you can't see that it's on that channel.)
  27.  
  28. Server List
  29.     This is another extremely important configuration window.
  30.     Without setting up a server, ShadowBot cannot connect to IRC. The Server List is an easy way to set up a list of servers that the bot can attempt to connect to.
  31.     In the largest portion of the window is taken up by the server list itself. A new bot will contain only one entry in the serverlist: "irc.server.com 6667 []" (this server doesn't work).
  32.     Each line in the server list is broken up into three parts: the server, the port, and the (optional) connection password. Thes three items are edited from the entry boxes at the bottom of the window.
  33.     The Add, Copy, and Delete buttons are used to Add entries to the serverlist, duplicate an entry, and delete entries from the list.
  34.  
  35. Owner Settings
  36.     The second most important of the configuration windows, Owner Settings allows you to configure the bot to recognize you as it’s owner.
  37.     Nick - Put your usual nickname here.
  38.     Hostmask - Put your hostmask here. If you’re not sure about your hostmask, see the section on hostmasks near the end of this file.
  39.     Email address (optional) - Allows you to set an email address that will be visible when someone asks the bot for your email address.
  40.     Infoline (optional) - A line the bot will send out when it sees you join a channel.
  41.     Real Name (optional) - People will see this line, if you have set it, when they do a WHOIS on you from the bot.
  42.     Password (optional) - Password used to identify yourself to the bot. Passwords are case sensitive.
  43.     Password is Required - If on, you MUST use the !ident [nick] password command to gain access. Otherwise, you only need to identify yourself when you're not using your normal hostmask.
  44.  
  45. Channel Settings
  46.     This window allows you to set what channels the bot is to join by default. The channel list on the right side of the window lets you set up to ten channels (IRC limitation). By selecting a channel from the list, its settings appear in the left side of the window.
  47.  
  48.     The Default channel - The default channel contains settings that will be used if you ask the bot to join channels not in its channel list. You cannot change its name. It is the first channel in the list, named "--Default--".
  49.     AutoJoin - If this is set, the bot automatically joins the channel.
  50.     Channel Modes - Channel modes can be set to either On, Off, or Ignore. When set to Ignore, the bot does not care what that particular mode is set to. If the mode is set to On, the bot will set that mode on if someone under a required access turns it off. The same is true if modes are set to Off: if someone turns it on, it is set back off.
  51.     Only Listed Users - If a user not in the user list enters, they are automaically kicked.
  52.     Strict Opping - Allows only opping of users in the bot's userlist. (Bitch mode on eggies.)
  53.     No Serverops - Deops any user gaining ops from a server.
  54.     CPING on Join - /CPING's users on join
  55.     Enable Idle Kick - Enables the idle kick for this channel.
  56.     +v on Join - Gives users voice on entering channel. Users on the shitlist don't get auto +v.
  57.     Disable Infoline - Disables the display of users inputlines
  58.     Disable Protection - Disables all user protection on this channel.
  59.     Auto-unban Bans - If this is checked, the bot unbans all bans after a specified time limit.
  60.     Beg For Ops - This will cause ShadowBot to beg for ops if it isn't opped in this channel.
  61.     Don't Kick On Bans - This will stop ShadowBot from kicking people out of a channel when they're banned.
  62.     Topic - If the Protect Topic button is on, the bot will try to keep the topic to the one specified.
  63.     Allow Alternate CC - You can specify an alternate command character for each channel, which can be used either with, or in place of, the default command character.
  64.     NOTE: If more than one bot in a channel has a dispute over modes or topics (i.e., one bot wants the topic +m and the other wants is -m), a Bot War may result. Deopping one of the bots and fixing its settings will fix the problem. If you have a Channel Service bot in your channel (for example, X or W on the Undernet), it's a Very Bad Idea to bring in a bot whose settings conflict, especially if the CService bot has a tendancy to be aggressive about its settings.
  65.  
  66. Access Levels
  67.     This window allows you to set the access levels required to activate the commands. -1 is the lowest and means that anyone may use the command. 0 means that anyone on the bot’s userlist may use the command. 1000 is the highest access level.
  68.     For a list of all command, open a DCC chat connection with ShadowBot and type '.HELP COMMANDS'.
  69.  
  70. Other Settings
  71.     This sets some of the other numeric settings the bot uses.
  72.     noIdleKick                                            Access Level for which users won't be kicked for idleing
  73.     idleMinutes                                        Number of minutes after which you can be kicked for idleing
  74.     modeOverride                           Access Level which allows you to override set channel modes
  75.     topicOverride                          Access Level which allows you to override set topic
  76.     noLagKick                                                «OBSOLETE»
  77.     lagSeconds                                            «OBSOLETE»
  78.     noLagNofifySecs                        «OBSOLETE»
  79.     infoLineTime                                    Wait at least this long before displaying someone's infoline again.
  80.     maintSecs                                                The length of time between runs through ShadowBot's maintenence loop.
  81.     initMem                                                        The initial number of memory records. If you are on channels with more
  82.                                                                                             than 50 people, it would be a good idea to increase this number so that
  83.                                                                                             it's larger than the average number of people on the channel. ShadowBot
  84.                                                                                             needs one memory record for each (unique) user it has to deal with, and it
  85.                                                                                             is much more efficient when it doesn't have to reallocate more memory
  86.                                                                                             to keep track of more users.
  87.     strictOpAl                                            If your access level is lower than this, you can't be opped if strict ops
  88.                                                                                             is on.
  89.     strictOpOverride                    If your access level is at least this, you can override the previous
  90.                                                                                                 setting.
  91.     autoSaveMins                                    How often ShadowBot writes the data files to disk.
  92.     ignoreTime                                            «UNIMPLEMENTED»
  93.     dccInactive                                        Kick people out of DCC after idling this long...
  94.     dccInactiveOverride        but don't kick them if their access is at least this.
  95.  
  96. Toggles
  97.     This allows you to set some of ShadowBot’s options. Although these settings should be self explanitory, you may wish to use balloon help.
  98.  
  99. Strings Editor
  100.     The Strings editor allows you to edit some of the strings the bot uses. The default strings are stored in the ShadowBot application, the strings actually used are stored in the Strings file. Any changes you make go into this file. If you delete it, the strings are reset the next time ShadowBot is opened.
  101.  
  102. Flood Control
  103.     This window allows you to set up ShadowBot's flood protection.
  104.  
  105. Logging Control
  106.     Allows you to have ShadowBot automatically log text in the channels its in, or view the current logging status.
  107.  
  108. Automessages
  109.     Allows you to setup time-delayed automatic messages.
  110.  
  111. Userlist
  112.     Allows you to locally edit the user list.
  113.  
  114. Shitlist
  115.     Allows you to locally edit shitlist entries.
  116.  
  117. Partyline Configuration
  118.     The partyline feature allows more than one user to open a DCC chat connection to your bot and talk in realtime, much like on an IRC server. Text going through the partyline is displayed in the Partyline Console.
  119.     ShadowBot's partyline is compatible with the one found in eggdrop bots, a common Unix bot. Because of this compatibility, ShadowBot has the ability to connect to eggdrop bot networks.
  120.     My Nick- This is the bot's username on the bot it's attempting to connect to.
  121.     Connect To- This is the name of the bot to connect to. Add bots to this list by making them bots in the userlist.
  122.     Bot Settings- Edits the bot's connection information.
  123.     Ping interval- How often to ping the remote bot if it's not sending text.
  124.     Access- In order to make ShadowBot respond as an Eggdrop bot would over a botnet, the "Master" and "Owner" access levels are required. These access levels define what level access you need to use some partyline commands.
  125.     Connect Automatically- Automatically connects to the botnet at launch.
  126.     Retry Delay- How often to retry a connection if it fails.
  127.     Accept Associations- The partyline allows 100,000 "channels"- 0 (the main partyline) to 99,999. It also allows these channels to have topics (associations). If you wish ShadowBot to enable the .ASSOC command locally and process ASSOC commands from other bots, you need to turn this option on. (Default is on.)
  128.     Allow Remote Boots- The .BOOT command allows you to remove someone from the botnet, if you have Master access or higher. This also allows you to boot people on other bots. To prevent users on other bots from booting people on this bot, turn this command off. (Default is on.) Users with "owner" access cannot be booted.
  129.     Password Not Required- When checked, disables the password requirment when opening DCC chat.
  130.     Currently Connected- Indicates if ShadowBot is currently connected to a botnet.
  131.  
  132.     To connect to the botnet, use the LINK command. To disconnect, use the UNLINK command.
  133. ---------
  134. Scripting and Plugins
  135.     ShadowBot has a scripting language that can be used to make auto-greets and new commands. See the files in the Plugin Docs folder for more information.
  136.  
  137. ---------
  138. Command List
  139.     For a list of commands and how to use them, open a DCC connection with ShadowBot and type ".HELP COMMANDS". You can also use the help command from the console.
  140.  
  141. ---------
  142. Authentication Passwords and Identification
  143.     ShadowBot only recognizes users in its userlist provided they meet the following criteria:
  144.     • Their hostmask matches one of their hostmasks in the bot and they have no password set.
  145.     • They have a password set and they identify themselves.
  146.  
  147.     Unless these two criteria are met, a user has no access.
  148.  
  149. Setting a Password
  150.     To set a password, use the newpass command:
  151.         newpass [oldpassword] newpassword
  152.     If you have no password set, you don't type in an old password, since you don't have one. If you had a previous password set, you need to enter both your old and your new passwords. This command must be messaged to the bot or entered via DCC chat. It will be ignored if you use it in the chanel.
  153.  
  154. Identifying yourself to the bot
  155.     To identify yourself to the bot if you are connecting with a userhost that doesn't match, use the ident command:
  156.         ident [nick] password
  157.     If your password matches, you are given access. You do not need to specify a nickname unless your nickname is different from the one in the userlist. This command must be messaged to the bot. It will be ignored if you use it in the chanel.
  158.  
  159. Setting up multiple hostmasks
  160.     To allow for the fact that users may wish to be automatically identified from more than one hostmask, ShadowBot allows you to add additional hostmasks. There are buttons in the Userlist and Owner Settings to allow this to be accomplished easily, however there are are commands that serve the same purpose:
  161.         adduserhost [nick] userhost
  162.         deluserhost [nick] userhost
  163. You need not specify a nickname if you are using these commands on yourself.
  164. ---------
  165. How to add users to the bot
  166. There are two ways to add users to the userlist: through the GUI usereditor, and the !ADD command.
  167.  
  168. Syntax for the !ADD command:
  169. !ADD channel usuNick userAtHost accessLevel [autoOp [protectionLevel [pwd]]]
  170.  
  171. For example, the following command:
  172.     !ADD * DShadow *!*DShadow@*.dial.umd.edu 1000 1 3 PASS
  173. translates into the following to the bot:
  174.     Add a new user
  175.     On all channels ("*")
  176.     With a nickname of DShadow
  177.     Whose hostmask is *!*DShadow@*.dial.umd.edu
  178.     With an access level of 1000
  179.     With an autoop level of 1 (or on)
  180.     With a protection level of 3
  181.     With an authentication password of PASS
  182.  
  183. NOTE: You should NEVER add more than one user with the same nick; there are several cases where ShadowBot does a search by nick, and will always stop at the first matching nick found. The userlist will not allow you to have more than one person with the same name.
  184. NOTE: The usual nick parameter allows the bot to recognize you when a user performs any command in which the nick may be used.
  185. NOTE: parameters after the access level do not need to be given. For example, if I didn’t specify anything after the access level, autoop would default to off, the protect level would be zero, and there would be no authentication password.
  186. NOTE: Authentication passwords are CASE SENSITIVE.
  187.  
  188. Removing users from the bot
  189.     To remove a user from the bot, check the 'Deleted' button in the userlist, or use the DEL command:
  190. !DEL usuNick
  191.  
  192.  This deletes anyone with the nick specified. Please note that this does not actually remove them from the userlist, it just marks them as deleted. This allows you to undelete them before someone else is added on top of them.
  193.  
  194. The autoop parameter
  195.     The autoop parameter is a boolen variable: either on or off. Only certain characters mean on. All others mean off. When the autoop parameter is processed, only the first character is examined. This means that "Y" and "Yes" mean the same thing. Capitilization doesn't matter
  196.     The ON characters
  197.         1
  198.         Y (Yes)
  199.         T (True)
  200.  
  201. ---------
  202. Hostmasks
  203.     The way ShadowBot recognizes users is by their userhost, which is sent to the bot each time someone writes a message in a channel or sends a message to the bot. This allows for identification of someone according to nick, username, and machine name. If you aren't sure of your machine name, you can get that information from a /whois on yourself. You set your nick and username from your IRC client.
  204.  
  205. Take me, for example:
  206.                             Nick: DShadow
  207.                             User name: DShadow
  208.                             Machine name: ascend4-38.dial.umd.edu
  209.  
  210.     The userhost for the above connection is DShadow!DShadow@ascend4-38.dial.umd.edu. Note the exclamation point between the nick and username and the at mark between the username and the machine name. Any time I say something in the channel, or do something that affects it (mode changes, kicks, etc), this entire string is sent by the server.
  211.  
  212.     Obviously, there is a problem with this. When used as a means of identification, it is valid only when my nick and username are DShadow and I'm on the modem connected to ascend4-38 on my ISP. So we use wildcards to replace portions of the userhost. For example, I would use the following hostmask in my bot to identify myself:
  213.  
  214.                     *!*DShadow@*.dial.umd.edu
  215.  
  216.     What this means is that anyone whose username ends in DShadow and is on any machine in the .dial.umd.edu domain is recognized by the bot. This allows for the fact that I might not always use the same nick or be connected to the same phone line. I could be more specific and use a mask like
  217.  
  218.                     *!*DShadow@ascend4-*.dial.umd.edu
  219.  
  220. which would only allow access if I used one specific modem pool. At school, when I have a static IP, I use the entire machine name in the mask. For example,
  221.  
  222.                     *!*DShadow@dshadow.dorm.umd.edu or *!*DShadow@terpmug.umd.edu
  223. ------------------------------------------------------------------------------------
  224. Special thanks to
  225. Olaf Titz- for writing Ircle 1.5.1, which ShadowBot is based on
  226. Elixer - the startup screen
  227. Stimmpy, Possible - unending torture in ShadowBot's infancy
  228. PowerUser, MacJedi, Possible, GregG_, Melkor, Tandronis- ShadowBot's first testers
  229. Peter N. Lewis - for the use of his MacTCP code
  230. irc.amug.org - ShadowBot's residence
  231. MacJedi - the icons
  232. Onno Tijdgat- for getting me through the Identd code and sharing quite a bit of other code that I would never have gotten on my own, and one kick-ass IRC client
  233.  
  234. How to contact me
  235. Email: dshadow@glue.umd.edu
  236. IRC: Undernet: DShadow, usually on #macintosh, #macnewbies, and #mac
  237. Snail Mail: John Bafford
  238.                                         6 Cedar Springs Ct.
  239.                                         Baltimore, MD 21228
  240.  
  241. The Fine Print
  242. No warranty is provided. Use at your own risk. What else do you want from a disclaimer?